I translate a part of the HACKER.DOC in french
first in text
second in html
bye
--
charles /  \
vidal  / ..|\
      (_\  |_)cvidal@ivsweb.com
      /  \@'
     /     \  http://www.chez.com/vidalc
 _  /  `   |
\\/  \  | _\
 \   /_ || \\
  \____)|_) \_)
-----------------------------------------
LA DOC DU BIDOUILLEUR

INTRODUCTION
________________________________________________________________________________

Ce document est pour tous ceux qui veulent modifier xlock (more), ajouter de
nouveaux modes, debugger , etc....

xlock kesako ?

xlock est une application pour X-windows qui emp�che l'acc�s d'un ou plusieurs
�crans. Il peut �tre envoy� manuellement ou plus commun�ment envoy�
automatiquement par un d�mon apr�s une p�riodes d'inactivit�.
Xlock cr�� une fen�tre couvrant enti�rement l'�cran, et capte tous �v�nements
pr�venant ainsi l'acc�s ext�rieur.
Quand une touche est press�e alors xlock affiche un message mais aussi le mode
dans une icone
(MODE_ICONIQUE) et demande votre mot de passe.
Lorsque l'�cran est lock� ( ferm� ), des images, des dessins, ou des animations
sont affich�es servant de screen-saver �vitant la d�gradation du phosphore.
Xlock fut d�velopp� chez Sun Micro System par Pack J Naughton.David Bagley l'a
repris et maintenu sous le nom de Xlockmore dans lequel d'innombrable mode ont
�t� ajout�, ainsi que la possibilit� d'afficher un mode dans une fen�tre et
aussi sur la root window.

________________________________________________________________________________
ORGANISATION GENERALE

xlock est organiser en deux partie.

1. le traitement de la ligne de commande, la cr�ation de fen�tre, le mot de
passe, etc ...

2 les modes: ils peuvent �tre coder de tel mani�re qu'il n'y a pas besoin de
faire appel � X pour la taille de la fen�tre, les couleurs ...
Une API est comprise dans xlock pour avoir tout les renseignements en ce qui
concerne l'�cran.
C'est dans cette partie que vous allez pouvoir ajouter d'autres modes.

L'architecture logiciel d'un mode est structur� en 4 sortes de fonctions:

-init:
celle-ci devra �tre appelle pour pr�parer le d�roulement d'un mode. Le mode
devra initialiser des tables de sinus
par exemple, allouer des ressources, m�moire entre autre, �tablir l'�tat initial
par des variables etc. ...
Cette fonction peut �tre appel� plusieurs fois et la fen�tre ou l'�cran peuvent avoir des taille diff�rentes.

-callback:
C'est la principale fonction, c'est la que est implement� le corps du mode.
 Elle est appel� p�riodiquement.
 Cette fonction ne doit pas occuper beaucoup de temps a s'ex�cuter.
Cette fonction peut etre appele dans deux contextes diff�rents:
 plein �cran ou en version icon. La fonction MI_IS_ICONIC vous dira dans
quelle contexte on se trouve.

-release:
Ici, cette fonction sera appel� si un autre mode est appel� ( random , et bouton
droit ), ou si xlock se termine.
Dans cette fonction, il faut d�sallouer la m�moire, X ressource, Pixmaps et
graphics context.

-refresh:
 Celle ci est appel� lorsque le dessin peut �tre abim�. Le mode doit repeindre
l'ensemble de la fen�tre.

-change: ???? <A FINIR>



________________________________________________________________________________
CONVERSION:
Le prototype de ces fonctions est d�fini dans mode.h et ressemble �:
	void typefonction _mode( ModeInfo *mode_info)
La structure mode_info est en lecture seule, et contient l'ensemble des
informations sur l'�cran.
Ne regardez pas les variables globales, n'�crasez pas ce pointeur.
Au lieu de faire des requetes pour conna�tre le num�ro de la couleur blanche
etc... , il y a des fonctions propres a xlock: utilisez les.




________________________________________________________________________________
L'AJOUT D'UN NOUVEAU MODE:

Ajoutons un nouveau mode appel� fadeplot:
Pour ce faire il faut d'abords ajouter dans mode.h
� extern ModeHook init_fadeplot;
extern ModeHook draw_fadeplot;
extern ModeHook release_fadeplot;
extern ModeHook refresh_fadeplot; �
les fonctions qui vont �tre cr��s.

� extern ModeSpecOpt fadeplot_opts; �
une structure qui ne m'a pas r�v�l� tous ces secrets.

mais aussi dans mode.c � cot� des autres fonctions , dans ce que j'appelle la
 tableau des modes:
 {"fadeplot", init_fadeplot, draw_fadeplot, release_fadeplot,
 refresh_fadeplot, init_fadeplot, NULL, &blank_opts, 17000, 1, 20, 1.0,
  "fadeplot", 0, NULL},

On passe ensuite � l'impl�mentation des fonctions proprement dit dans un fichier
que l'on appellera fadeplot.c.
Il est �vident qu'il faudra modifier le Makefile ( Pour cela je vous laisse
faire :).

Dans ces fonctions, � partir de la structure ModeInfo, on va obtenir des
informations sur l'�cran qui sont indispensables pour la suite

MI_WIDTH(mi) et MI_HEIGHT(mi) 	vont nous donn� la taille de l'�cran.
Display    *display    = MI_DISPLAY(mi);	d�livre le display
Window      window = MI_WINDOW(mi);	  d�livre l'identificateur de la fen�tre
GC          gc               = MI_GC(mi);    donne le graphics context courant
XSetForeground(display, gc, MI_BLACK_PIXEL(mi));
				Mettre la couleur du trac� en noir
XSetForeground(display, gc, MI_WHITE_PIXEL(mi));
				 Mettre la couleur du trac� en blanc

MI_IS_ICONIC(mi)		permet de savoir si on est pass� en phase
								password.
NUMCOLORS			Donne le nombre de couleur


Oubliez pas apr�s avoir dessin� l'ensemble de faire Xflush(display),
ce qui permettra d'afficher r�ellement votre graphisme sur l'�cran.
La cr�ation d'un nouveau mode s'�ffectue souvent en r�cup�rant le squelette
d'un autre et de le modifier � sa volont�.
N'h�sitez pas a � regarder le code des autres modes, c'est souvent tr�s
instructifs.
Dernierement on peut utiliser la librairie mesa (la libraire GNU OpenGL de
silicon Graphics) dans xlock.
Voila j'espere que vous prendrez plaisir a ajouter des nouveaux modes � xlock,
 un petit conseil le mainteneur de xlock est un fan de casse t�te et compagnie.
Bon Xlock.

Charles VIDAL: cvidal@ivsweb.com
mode flag, fadeplot, circle
createur de xmxlock : GUI launcher de xlockmore.

------------------------------------------------------

<HTML>
<HEAD>
<TITLE>Xlock french hacker</TITLE>
</HEAD>
<BODY>
<Center><H1>XLOCK FRENCH HACKER</H1></Center>
<BR>
<H2>INTRODUCTION</H2>
<HR>
Ce document est pour tous ceux qui veulent modifier xlock (more), ajouter de nouveaux modes, debugger , etc....

<H2>xlock kesako ?</H2>

xlock est une application pour X-windows qui emp�che l�acc�s d�un ou plusieurs �crans. Il peut �tre envoy� manuellement ou plus commun�ment envoy� automatiquement par un d�mon apr�s une p�riodes d�inactivit�.
 Xlock cr�� une fen�tre couvrant enti�rement l��cran, et capte tous �v�nements pr�venant ainsi l�acc�s ext�rieur.
Quand une touche est press�e alors xlock affiche un message mais aussi le mode dans une icone (MODE_ICONIQUE) et demande votre mot de passe.<p>
Lorsque l��cran est lock� ( ferm� ), des images, des dessins, ou des animations sont affich�es servant de screen-saver �vitant la d�gradation du phosphore.
Xlock fut d�velopp� chez Sun Micro System par Pack J Naughton.David Bagley l�a repris et maintenu sous le nom de Xlockmore dans lequel d�innombrable mode ont �t� ajout�, ainsi que la possibilit� d�afficher un mode dans une fen�tre et aussi sur la root window ou d�afficher sequentiellement plusieur mode par l�option random et par l�appuis du bouton du millieu.<p>
Il existe des terminaux X avec plusieur ecrans gere par un seul terminal, alors le m�me mode s�affichera sur plusieur ecran. On peut toutefois faire des effets, comme une balle passant de lui a l�autre.

<HR>
<H2>ORGANISATION GENERALE</H2>

xlock est organiser en deux partie.<p>

<OL>
<LI> le traitement de la ligne de commande, la cr�ation de fen�tre(s), le mot de passe, etc ...
<LI> les modes: ils peuvent �tre coder de tel mani�re qu�il n�y a pas besoin de faire appel � X pour la taille de la fen�tre, les couleurs ... Une API est comprise dans xlock pour avoir tout les renseignements en ce qui concerne l��cran.C�est dans cette
</OL>
<HR>
<B>L�architecture logiciel d�un mode est structur� en 4 sortes de fonctions:</B>
<UL>
<LI><U><B>-init:</B></U>
celle-ci devra �tre appelle pour pr�parer le d�roulement d�un mode. Le mode devra initialiser des tables de sinus par exemple, allouer des ressources, m�moire entre autre, �tablir l��tat initial par des variables etc. ...
Cette fonction peut �tre appel� plusieurs fois et la fen�tre ou l��cran peuvent avoir des taille diff�rentes.<p>

<LI><U><B>-callback:</B></U>
C�est la principale fonction, c�est la que est implement� le corps du mode. Elle est appel� p�riodiquement. Cette fonction ne doit pas occuper beaucoup de temps a s�ex�cuter surtout si elle a plusieur ecran s�occuper.
Cette fonction peut etre appele dans deux contextes diff�rents:
 plein �cran ou en version icon. La fonction MI_IS_ICONIC vous dira dans quelle contexte on se trouve.
la fonction init_mode est toujours appelle avant la fonction callback.
On peut choisir de faire quelque chose a chaque appelle, ou de compter le nombre d�appelle, et puis de modifier l�ecran periodiquement.<p>

<LI><U><B>-release: </B></U>
Ici, cette fonction sera appel� si un autre mode est appel� ( random , et bouton droit ), ou si xlock se termine. Dans cette fonction, il faut d�sallouer la m�moire, X ressource, Pixmaps et graphics context.
<p>
<LI><U><B>-refresh:</B></U>
 Celle ci est appel� lorsque le dessin peut �tre abim�. Le mode doit repeindre l�ensemble de la fen�tre.
Aucun information sur la partie de l�ecran endomage n�est delivre.
<p>
<LI><U><B>-change:</B></U> Dans la version courante, seule le mode random utilise cette fonctionnalite. Cet fonction est appele lorsque que l�on change de mode par l�appuie du boutton du millieu. Il est laisse a l�imagination de chacun en ce qui conserne
</UL>


<HR>
<H2>CONVENTION:</H2>
Le prototype de ces fonctions est d�fini dans mode.h et ressemble �:<p>
<Center>	void typefonction _mode( ModeInfo *mode_info)</Center>
La structure mode_info est en lecture seule, et contient l�ensemble des informations sur l��cran. Ne regardez pas les variables globales, n��crasez pas ce pointeur. Au lieu de faire des requetes pour conna�tre le num�ro de la couleur blanche etc... , il y a des fonctions propres a xlock: utilisez les. Si vous utilisez les informations passe en parametre des fonctions du modes ( voir ci dessus ), votre code sera toujours correcte.
Le temps entre chaque appelle  de fonctions est en milliseconde.

<HR>
<H2>L�AJOUT D�UN NOUVEAU MODE:</H2>

Ajoutons un nouveau mode appel� <A HREF="file:fadeplot.txt">fadeplot</A>:<p>
Pour ce faire il faut d�abords ajouter dans mode.h<p>
� extern ModeHook init_fadeplot;<p>
extern ModeHook draw_fadeplot;<p>
extern ModeHook release_fadeplot;<p>
extern ModeHook refresh_fadeplot; �<p>
les fonctions qui vont �tre cr��s.
<p>
� extern ModeSpecOpt fadeplot_opts; �<p>
une structure qui ne m�a pas r�v�l� tous ces secrets.<p>

mais aussi dans mode.c � cot� des autres fonctions , dans ce que j�appelle le tableau des modes:<p>
 {"fadeplot", init_fadeplot, draw_fadeplot, release_fadeplot,
 refresh_fadeplot, init_fadeplot, NULL, &blank_opts, 17000, 1, 20, 1.0,
  "fadeplot", 0, NULL},<p>

On passe ensuite � l�impl�mentation des fonctions proprement dit dans un fichier que l�on appellera fadeplot.c.<p>
Il est �vident qu�il faudra modifier le Makefile ( Pour cela je vous laisse faire :).<p>
Dans ces fonctions, � partir de la structure ModeInfo ( mode.h ) , on va obtenir des informations sur l��cran qui sont indispensables pour la suite.<p>

<TABLE Border=1>
<CAPTION><B>fonction</B></CAPTION>
<TR><TD>MI_WIDTH(mi) et MI_HEIGHT(mi)</TD> 	<TD>vont nous donn� la taille de l��cran</TD></TR>.
<TR><TD>Display    *display    = MI_DISPLAY(mi);</TD>	<TD>d�livre le display</TD></TR>
<TR>	<TD>	         MI_SCREEN	</TD>	<TD>d�livre le screen</TD></TR>
<TR><TD>Window      window = MI_WINDOW(mi)</TD>;	<TD>d�livre l�identificateur de la fen�tre</TD></TR>
<TR><TD>GC          gc               = MI_GC(mi);</TD>	<TD>donne le graphics context courant</TD></TR>
<TR>	        <TD>MI_DELAY</TD>		<TD>    donne le delai (microsec.) entre callbacks</TD></TR>
<TR>        <TD>MI_CMAP</TD>		<TD>donne la table des couleurs</TD></TR>
<TR><TD>XSetForeground(display, gc, MI_BLACK_PIXEL(mi));</TD> 	<TD>Mettre la couleur du trac� en noir</TD></TR>
<TR><TD>XSetForeground(display, gc, MI_WHITE_PIXEL(mi));</TD> <TD>Mettre la couleur du trac� en blanc</TD></TR>
<TR><TD>MI_IS_ICONIC(mi)	</TD>	<TD>permet de savoir si on est pass� en phase password. </TD></TR>
</TABLE>

<TABLE Border=1>
<CAPTION><B>variable</B></CAPTION>
<TR><TD>MI_IS_MONO	</TD>		<TD>l�ecran est monochrome</TD></TR>
<TR><TD>MI_IS_INWINDOW</TD>		<TD>le mode s�affiche dans un fenetre reguliere</TD></TR>
<TR><TD>MI_IS_INROOT	</TD>		<TD>le mode s�affiche sur la root windows</TD></TR>
<TR><TD>NUMCOLORS</TD>			<TD>Donne le nombre de couleur</TD></TR>
</TABLE>


Oubliez pas apr�s avoir dessin� l�ensemble de faire Xflush(display), ce qui permettra d�afficher r�ellement votre graphisme sur l��cran.
La cr�ation d�un nouveau mode s��ffectue souvent en r�cup�rant le squelette d�un autre et de le modifier � sa volont�.
N�h�sitez pas a � regarder le code des autres modes, c�est souvent tr�s instructifs.
<HR>
<H2>Perspective:</H2>
Dernierement on peut utiliser la librairie mesa (la libraire OpenGL de silicon GNU) dans xlock, quelqu�un s�est propose de faire le screen-saver tube de Win NT.
Je pense qu�il serait interressant de joindre a xlock un langage simple ( genre logo un peu plus evolue).
<HR>
<H2>Reference: </H2>
HACKERS.GUIDE qui se trouve dans le repertoire docs ( j�ai essaye de le traduire :)<p>
	    X_Window programmation avec les Xt-Intrinsics Douglas A YOUNG MASSON PARIS.<p>
<HR>
Voila j�espere que vous prendrez plaisir a ajouter des nouveaux modes � xlock; c�est une maniere de programmer facilement des graphismes sous X11. Un petit conseil le mainteneur de xlock est un fan de casse t�te et compagnie.
Bon Xlock.
<p>
Charles VIDAL: cvidal@ivsweb.com<p>
mode flag, fadeplot, bubble<p>
createur de xmxlock : GUI launcher de xlockmore.<p>

</BODY>
</HTML>
